---
title: Invoke job by client id, key/value parameters
summary: Gates a caller-supplied job against the uc4.rules allow/deny list and forwards it, with caller-supplied key/value parameters passed through unchanged, to the downstream UC4 scheduling service.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-22
operation_id: OP-008
trigger: A SOAP caller invokes ExecuteJobWithParametersAndClientId on the UC4 route
---

# OP-008: Invoke job by client id, key/value parameters

This process backs the `ExecuteJobWithParametersAndClientId` operation. It follows the same shape as [OP-006](execute-job-with-values-and-client-id.md), the canonical flow, but omits the positional-value naming step: caller-supplied key/value parameters are forwarded to the downstream service unchanged. **Transaction boundary: none.**

| Field | Value |
| --- | --- |
| **Operation ID** | OP-008 |
| **Trigger** | SOAP caller invokes `ExecuteJobWithParametersAndClientId` |
| **Entry operation** | [`ExecuteJobWithParametersAndClientId`](../contracts/uc4-service.md#executejobwithparametersandclientid) |
| **Owning component** | `UC4Service.ExecuteJobWithParametersAndClientId` |
| **Inputs** | `environment` (`short`), `jobName` (`string`), `parameters` (key/value collection) |
| **Outputs** | `UC4Result` — the mapped downstream result, or an empty result if the job is blocked |
| **Failure behavior** | An unhandled exception is surfaced by the WCF framework as a generic SOAP fault carrying full exception detail |

## Request and response

| Direction | Element | Type | Declared in | Notes |
| --- | --- | --- | --- | --- |
| Request | `environment` | `short` | `UC4Service.cs` | Client id identifying the environment |
| Request | `jobName` | `string` | `UC4Service.cs` | The job to invoke |
| Request | `parameters` | key/value collection | `UC4Service.cs` | Passed through to the downstream service unchanged — no `arg1`/`arg2`-style positional naming applied |
| Response | `<return>` | `UC4Result`* | `UC4Service.cs` | Mapped downstream result, or an empty `UC4Result` if blocked |

## Steps

1. WCF dispatcher activates `UC4Service` as in [OP-006](execute-job-with-values-and-client-id.md#steps).
2. Log the invocation at `INFO` — [BR-UC4-008](../business-rules.md#br-uc4-008-every-invocation-is-traced-at-info).
3. `Enforce.ArgumentNotNull` rejects a null `jobName` — [BR-UC4-004](../business-rules.md#br-uc4-004-job-name-must-not-be-null).
   - On failure: throws → detailed WCF fault.
4. `UC4Service.IsJobAllowed` reads `uc4.rules` and evaluates the gate exactly as in [OP-006 step 4-6](execute-job-with-values-and-client-id.md#steps) — [BR-UC4-001](../business-rules.md#br-uc4-001-job-allowed-by-uc4-rules-document), [BR-UC4-002](../business-rules.md#br-uc4-002-default-allow-for-unmatched-environment), [BR-UC4-003](../business-rules.md#br-uc4-003-rule-evaluation-order-and-match-type).
   - On failure: a missing/malformed rules document or invalid regex throws → detailed WCF fault.*
5. If not allowed: return `new UC4Result()`, discarding the explanatory message — [BR-UC4-005](../business-rules.md#br-uc4-005-blocked-job-returns-empty-result-with-no-explanation). Not a fault.
   - Otherwise: continue to step 6.
6. Resolve the downstream address and stamp the host identity, exactly as in [OP-006 step 9](execute-job-with-values-and-client-id.md#steps) — [BR-UC4-010](../business-rules.md#br-uc4-010-downstream-service-address-resolved-per-call), [BR-UC4-011](../business-rules.md#br-uc4-011-forwarded-job-stamped-with-host-identity).

   > **Origin**: Step 6's downstream client construction is implemented in `SAIF.Web.API.Clients` / `SAIF.Services.UC4` (external packages, not documented by this run) and executed within this operation.*
   - On failure: a missing setting or unreachable address throws → detailed WCF fault.
7. Forward the caller-supplied `parameters` unchanged to the downstream `IUC4Service.ExecuteJob`.
   - On failure: a downstream exception propagates unchanged → detailed WCF fault.
8. Map the downstream result field-by-field onto the published `UC4Result` — [BR-UC4-012](../business-rules.md#br-uc4-012-downstream-result-mapped-field-by-field).
   - On failure: a null downstream result may throw.*
9. WCF dispatcher serializes the `UC4Result` and returns it.

## Process flow

```mermaid
flowchart TD
    A["Activate UC4Service"] --> B["Log invocation<br>at INFO"]
    B --> C["Enforce jobName<br>not null"]
    C -->|"null"| CFAULT["Detailed WCF fault"]
    C --> D["Read uc4.rules,<br>evaluate gate"]
    D -->|"read/parse fails"| DFAULT["Detailed WCF fault"]
    D --> E{"Allowed?"}
    E -->|"No"| F["Return empty UC4Result<br>message discarded"]
    E -->|"Yes"| G["Resolve downstream address,<br>stamp host identity"]
    G -->|"missing setting"| GFAULT["Detailed WCF fault"]
    G --> H["Forward parameters unchanged<br>to downstream service"]
    H -->|"downstream throws"| HFAULT["Detailed WCF fault"]
    H --> I["Map downstream result<br>to published UC4Result"]
    I --> J["Serialize and return"]
    F --> J
```

## Transaction and side effects

| Aspect | Finding |
| --- | --- |
| Unit of work | None |
| Commit point | Not applicable — no persistence |
| Records written | None locally |
| Downstream calls | `UC4Client.ScheduleJob` → downstream UC4 scheduling service |
| Shared state touched | None |
| Repeat-call behavior | Not idempotent from the host's perspective |

## Faults and error handling

| Failure | Fault type the caller receives | Produced by | Source |
| --- | --- | --- | --- |
| `jobName` null | Generic SOAP fault, full exception detail | The WCF framework | `UC4Service.cs` |
| `uc4.rules` missing/malformed or invalid regex | Generic SOAP fault, full exception detail | The WCF framework | `UC4Service.cs` |
| Downstream construction/call failure | Generic SOAP fault, full exception detail | The WCF framework | `Uc4Client.cs` |

`UC4Service` carries `[LogErrorBehavior]`, an external `IServiceBehavior` whose implementation is not in this repository; its contribution is observability, not fault shaping — see [Faults and error pipeline](../faults.md).

## Authorization

| Requirement | Enforced by | Source | Applies to |
| --- | --- | --- | --- |
| [None in code](../authentication-authorization.md#access-requirements-per-operation) | Nothing — no attribute or programmatic check exists | `UC4Service.cs` | This operation |

## Related documentation
- [Index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Activation and hosting](../activation-hosting.md)
- [Operations](../operations.md)
- [Faults and error pipeline](../faults.md)
- [Authentication and authorization](../authentication-authorization.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Operational runbook](../operational-runbook.md)
- [Tech debt](../tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Sources
- `src/WCF/SAIF.Services.WCF.UC4.Host/UC4Service.cs`
- `src/WCF/SAIF.Services.WCF.UC4.Host/Uc4Client.cs`